<?php
/**
 *  Form Interface
 *  Implements ArrayAccess much as Javascript form, ie.
 *      - accessing form[attr] will (which matches first):
 *          - return a form attribute (name,action,renderer,parser etc)
 *          - return an element object, which is otherwise accessible via getElements
 *          - throw an error
 *      - modifying form[attr] will accordingly set an element, but throw exception if it is not a element object
 *  Form is also iterable over its elements using IteratorAggregate
 *
 */
interface Yz_Form_Interface
    extends ArrayAccess
{

    /*
     * the task of renderer ?
    public function getName();
    public function getEncType();
    public function getAction();
    public function getMethod();
    */
    /**
     *  required to use the following in templates: form.elements.xxx
     *  @return Yz_Hash (a copy of the array of elements)
     */
    public function getElements();
    public function assignElements( $elements );
    /** getValues()
     *  required to use the following in templates: form.values.xxx
     *  @return Yz_Hash (a copy of values)
     */
    public function getValues();

    /**
     *  Also a setter may be used: $form->values = x
     *
     */
    public function assignValues($values);
    /**
     *  A renderer defines:
     *  - the visual wrapping ("design") of form elements
     *  - the order of elements
     *  - the relationships among elements (eg. If A=x, skip B)
     *  - the SUBMIT element
     */
    /**
     *  A parser defines:
     *  - the "requiredness" of elements
     *  - the relationships among elements (eg. If A=x, skip B)
     *  - external parameters which affect the parsing (resubmission, delays, etc)
     */

    public function render(Yz_Template_Interface $template);

    /**
     *  It would be convenient to throw exception from the parser, but
     *  we require that the parser determine all possible errors before
     *  finishing work.
     *
     *  @return chainable
     *  @throw exception
     */
    public function parse($values);


}
